<html>
<head>
    <title>SIMILE | Timeline | Documentation | Timeline class</title>
    <link rel='stylesheet' href='styles.css' type='text/css' />
</head>
<body>
<ul id="path">
  <li><a href="http://simile.mit.edu/" title="Home">SIMILE</a></li>
  <li><a href="../" title="Timeline">Timeline</a></li>
  <li><a href="./" title="Documentation">Documentation</a></li>
  <li><span>Timeline class</span></li>
</ul>

<div id="body">
    <h1>Timeline class</h1>
    
    <h2>Interface</h2>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">HORIZONTAL</span>
        </div>
        <div class="itf-member-description">
            <em>static</em>, 0.
        </div>
    </div>
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">VERTICAL</span>
        </div>
        <div class="itf-member-description">
            <em>static</em>, 1.
        </div>
    </div>

    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">create</span>
            ( <span class="itf-member-param">div</span>,
            <span class="itf-member-param">bandInfos</span>,
            <span class="itf-member-param">orientation</span> )
        </div>
        <div class="itf-member-description">
            <p><em>static</em>, return a timeline created inside the given 
                <span class="itf-member-param">div</span> in the given
                <span class="itf-member-param">orientation</span> (or
                horizontal by default) and containing 
                <a href="bands.html"><em>bands</em></a> initialized based on the settings
                in the <span class="itf-member-param">bandInfos</span>
                array.
            </p>
            
            <p>Each element of <span class="itf-member-param">bandInfos</span>
                is an object with the following fields:
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">width</span>
                    </div>
                    <div class="itf-member-description">
                        <em>required</em>, how much of the timeline's space this band
                        takes up, expressed as a percent in a string, e.g.,
                        <span class="code">"30%"</span>.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">eventSource</span>
                    </div>
                    <div class="itf-member-description">
                        <em>required</em>, an <a href="event-sources.html"><em>event source</em></a>
                        that provides events to be painted on this band, e.g.,
                        <span class="code">new Timeline.DefaultEventSource()</span>.
                        It can be <span class="code">null</span>, which means
                        the band is empty.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">timeZone</span>
                    </div>
                    <div class="itf-member-description">
                        <em>required</em>, a number specifying the time zone in
                        which the band will be marked with date/time intervals. For
                        example, to have hourly labels on the band painted by
                        Eastern Standard Time, specify <span class="code">-5</span>.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">ether</span>
                    </div>
                    <div class="itf-member-description">
                        <em>required</em>, an <a href="ethers.html"><em>ether</em></a>.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">etherPainter</span>
                    </div>
                    <div class="itf-member-description">
                        <em>required</em>, an <a href="ether-painters.html"><em>ether painter</em></a>.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">eventPainter</span>
                    </div>
                    <div class="itf-member-description">
                        <em>required</em>, an <a href="event-painters.html"><em>event painters</em></a>.
                    </div>
                </div>
                You can use the static utility methods 
                <span class="itf-member-name">createBandInfo</span> and
                <span class="itf-member-name">createHotZoneBandInfo</span>
                below to create elements of <span class="itf-member-param">bandInfos</span>,
                or you can construct them yourself.
            </p>
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">createBandInfo</span>
            ( <span class="itf-member-param">params</span> )
        </div>
        <div class="itf-member-description">
            <p><em>static</em>, create an object whose fields store various
                settings to initialize a <a href="bands.html"><em>band</em></a>
                that will have a <a href="linear-ether.html">linear ether</a>.
                Some initialization settings are read directly from the fields of 
                <span class="itf-member-param">params</span>, some are constructed
                from the fields of <span class="itf-member-param">params</span>,
                and some are filled in by default. This is a utility function
                for your convenience&mdash;you don't have to use it to create
                a band.
            </p>
            <p><span class="itf-member-param">params</span> is an object with
                the following fields (in no particular order):
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">width</span>
                    </div>
                    <div class="itf-member-description">
                        <em>required</em>, how much of the timeline's space this band
                        takes up, expressed as a percent in a string, e.g.,
                        <span class="code">"30%"</span>.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">intervalUnit</span>
                    </div>
                    <div class="itf-member-description">
                        <em>required</em>, a time unit from 
                        <span class="code">Timeline.<a href="date-time.html">DateTime</a></span>,
                        e.g., <span class="code">Timeline.DateTime.WEEK</span>.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">intervalPixels</span>
                    </div>
                    <div class="itf-member-description">
                        <em>required</em>, the number of pixels that the time unit above
                        is mapped to, e.g., <span class="code">100</span>.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">eventSource</span>
                    </div>
                    <div class="itf-member-description">
                        <em>optional</em>, an <a href="event-sources.html"><em>event source</em></a>
                        that provides events to be painted on this band, e.g.,
                        <span class="code">new Timeline.DefaultEventSource()</span>.
                        The default is <span class="code">null</span>, which means
                        the band is empty.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">theme</span>
                    </div>
                    <div class="itf-member-description">
                        <em>optional</em>, a <a href="themes.html"><em>theme</em></a>
                        that provides visual setting defaults for how the band's visual
                        elements are to be painted, e.g.,
                        <span class="code">Timeline.ClassicTheme.create()</span>.
                        The default is <span class="code">Timeline.getDefaultTheme()</span>.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">date</span>
                    </div>
                    <div class="itf-member-description">
                        <em>optional</em>, a <span class="code">String</span> or
                        a <span class="code">Date</span> (to be parsed by
                        <span class="code">Timeline.<a href="date-time.html">DateTime</a>.parseGregorianDateTime()</span>)
                        on which the band should be centered initially. The
                        default is the current date/time when 
                        <span class="code">Timeline.createBandInfo()</span> is called.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">timeZone</span>
                    </div>
                    <div class="itf-member-description">
                        <em>optional</em>, a number specifying the time zone in
                        which the band will be marked with date/time intervals. For
                        example, to have hourly labels on the band painted by
                        Eastern Standard Time, specify <span class="code">-5</span>.
                        The default is <span class="code">0</span>, meaning GMT.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">showEventText</span>
                    </div>
                    <div class="itf-member-description">
                        <em>optional</em>, a boolean specifying whether event titles
                        are to be painted. The default is true.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">trackGap</span>
                    </div>
                    <div class="itf-member-description">
                        <em>optional</em>, the number of <span class="code">em</span>
                        (dependent on the current font) to be left between adjacent
                        tracks on which events are painted. The default value is
                        retrieved from the provided or default theme. E.g.,
                        <span class="code">0.5</span>.
                    </div>
                </div>
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">trackHeight</span>
                    </div>
                    <div class="itf-member-description">
                        <em>optional</em>, the height of each track in <span class="code">em</span>
                        (dependent on the current font). The default value is
                        retrieved from the provided or default theme. E.g.,
                        <span class="code">1.5</span>.
                    </div>
                </div>
            </p>
        </div>
    </div>

    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">createHotZoneBandInfo</span>
            ( <span class="itf-member-param">params</span> )
        </div>
        <div class="itf-member-description">
            <p><em>static</em>, create an object whose fields store various
                settings to initialize a <a href="bands.html"><em>band</em></a>
                that will have a <a href="hot-zone-ether.html">hot-zone ether</a>.
                It works much like the static method
                <span class="itf-member-name">createBandInfo</span> above,
                except that <span class="itf-member-param">params</span> needs
                one extra field:
                <div class="itf-member">
                    <div class="itf-member-prototype">
                        <span class="itf-member-name">zones</span>
                    </div>
                    <div class="itf-member-description">
                        <em>required</em>, an array describing the hot zones. Each element of
                        this array is an object with the following fields:
                        
                        <div class="itf-member">
                            <div class="itf-member-prototype">
                                <span class="itf-member-name">startTime</span>
                            </div>
                            <div class="itf-member-description">
                                <em>required</em>, a <span class="code">String</span> or a
                                <span class="code">Date</span> object that specifies the
                                beginning date/time of the zone. It is parsed by 
                                <span class="code">Timeline.<a href="date-time.html">DateTime</a>.parseGregorianDateTime()</span>
                                to get a <span class="code">Date</span> object.
                            </div>
                        </div>
                        
                        <div class="itf-member">
                            <div class="itf-member-prototype">
                                <span class="itf-member-name">endTime</span>
                            </div>
                            <div class="itf-member-description">
                                <em>required</em>, a <span class="code">String</span> or a
                                <span class="code">Date</span> object that specifies the
                                ending date/time of the zone. It is parsed by 
                                <span class="code">Timeline.<a href="date-time.html">DateTime</a>.parseGregorianDateTime()</span>
                                to get a <span class="code">Date</span> object.
                            </div>
                        </div>
                        
                        <div class="itf-member">
                            <div class="itf-member-prototype">
                                <span class="itf-member-name">magnify</span>
                            </div>
                            <div class="itf-member-description">
                                <em>required</em>, a number specifying the magnification
                                of the mapping in this zone. A greater-than-1 number causes
                                more pixels to be mapped to the same time interval, resulting
                                in a zoom-in effect.
                            </div>
                        </div>
                        
                        <div class="itf-member">
                            <div class="itf-member-prototype">
                                <span class="itf-member-name">unit</span>
                            </div>
                            <div class="itf-member-description">
                                <em>required</em>, one of the Gregorian calendar unit defined in
                                <span class="code">Timeline.<a href="date-time.html">DateTime</a></span>,
                                e.g., <span class="code">Timeline.<a href="date-time.html">DateTime</a>.MINUTE</span>.
                                This argument specifies the interval at which ticks and labels
                                are painted on the band's background <em>inside this hot-zone</em>.
                            </div>
                        </div>
                        
                        <div class="itf-member">
                            <div class="itf-member-prototype">
                                <span class="itf-member-name">multiple</span>
                            </div>
                            <div class="itf-member-description">
                                <em>optional</em>, default to 1. A label is painted for every
                                <span class="itf-member-name">multiple</span> of
                                <span class="itf-member-name">unit</span>. For example, if
                                <span class="itf-member-name">unit</span> is 
                                <span class="code">Timeline.<a href="date-time.html">DateTime</a>.MINUTE</span> and
                                <span class="itf-member-name">multiple</span> is 15, then there
                                is a label for every 15 minutes (i.e., 15, 30, 45,...).
                            </div>
                        </div>
                    </div>
                </div>
            </p>
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">getDefaultTheme</span>
            ()
        </div>
        <div class="itf-member-description">
            <em>static</em>, return the default <a href="themes.html">theme</a>.
        </div>
    </div>

    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">setDefaultTheme</span>
            ( <span class="itf-member-param">theme</span> )
        </div>
        <div class="itf-member-description">
            <em>static</em>, set the default <a href="themes.html">theme</a>.
        </div>
    </div>

    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">loadXML</span>
            ( <span class="itf-member-param">url</span>, 
            <span class="itf-member-param">f</span> )
        </div>
        <div class="itf-member-description">
            <em>static</em>, asynchronously load an XML file at the given
            <span class="code">url</span> and then call 
            <span class="code">f</span> to process it.
            <span class="code">f</span> is passed 2 parameters:
            an XML document object and <span class="code">url</span>.
        </div>
    </div>

    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">isHorizontal</span>
            ()
        </div>
        <div class="itf-member-description">
            Return whether this timeline is horizontal.
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">isVertical</span>
            ()
        </div>
        <div class="itf-member-description">
            Return whether this timeline is vertical.
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">getDocument</span>
            ()
        </div>
        <div class="itf-member-description">
            Return the HTML document that this timeline belongs to.
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">getBandCount</span>
            ()
        </div>
        <div class="itf-member-description">
            Return the number of bands in this timeline.
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">getBand</span>
            ( <span class="itf-member-param">index</span> )
        </div>
        <div class="itf-member-description">
            Return the <a href="bands.html">band</a> at the given index.
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">layout</span>
            ()
        </div>
        <div class="itf-member-description">
            Re-lay out the timeline. Call this when the size of the timeline
            has changed.
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">paint</span>
            ()
        </div>
        <div class="itf-member-description">
            Re-paint the timeline. Call this when you want to force a repaint,
            say, to update event highlights and filters.
        </div>
    </div>

    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">getPixelLength</span>
            ()
        </div>
        <div class="itf-member-description">
            Return the timeline <span class="html">div</span>'s width
            if the timeline is horizontal, and height if the timeline
            is vertical. In other words, it returns the scrolling
            dimension of the timeline.
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">getPixelWidth</span>
            ()
        </div>
        <div class="itf-member-description">
            Return the timeline <span class="html">div</span>'s height
            if the timeline is horizontal, and width if the timeline
            is vertical. In other words, it returns the non-scrolling
            dimension of the timeline.
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">addDiv</span>
            ( <span class="itf-member-param">div</span> )
        </div>
        <div class="itf-member-description">
            Add the given <span class="itf-member-param">div</span> to the
            timeline's <span class="html">div</span>.
        </div>
    </div>
    
    <div class="itf-member">
        <div class="itf-member-prototype">
            <span class="itf-member-name">removeDiv</span>
            ( <span class="itf-member-param">div</span> )
        </div>
        <div class="itf-member-description">
            Remove the given <span class="itf-member-param">div</span> from the
            timeline's <span class="html">div</span>.
        </div>
    </div>
</div>
</body>
</html>